DECKeybd.doc                                               June, 1989
  
Introduction:

I'm typing this on a DEC LK201 keyboard connected to an Atari 1040ST
through the midi port.  Now I won't have to get a Mega to have a
decent, detachable, keyboard!  Besides, this keyboard has a better
layout and ( IMHO ) feel than the one that comes with a Mega.  

One of reason that I started using ST's was that its keyboard layout is
almost identical to a DEC keyboard.  Since my microcomputers spend a lot
of time acting as terminals talking to VAX computer systems, the
compatible keyboard layout is very important to me.  On the other hand,
I have always hated the feel of  the ST keyboard.  I think it is the
ST's worst feature.  Now I have been able to keep the layout and get
much better feel in a detached keyboard.

LK201s keyboards are used on all current DEC products, including
terminals and workstations. Moreover, they were used on the DEC Rainbow
PC's and on the previous generation of DEC terminals.  As a result,
they are fairly common at ham and computer fests. You could also get a
new one from DEC as a replacement part, albeit for too much money!

The obvious choice for an external ST keyboard would be an extended PC
keyboard.  Its layout is fairly close to the ST's, and it is relative
cheap and very available.  Unfortuately, its electrical interface is
quite incompatible with any of the Atari's ports. PC keyboard use with
the ST would require a complicated external interface adapter.  I don't
know if anyone has done it, but I decided it wasn't worth the trouble.
On the other hand, the LK201 keyboard can be wired directly to either
the serial or midi ports. 

LK201s conform to RS-423 standards at 4800 baud, 8 bits, no parity, one
stop bit.  They send a single byte of code ( a scan code ) for most key
presses, only the shift and control keys send codes on both down and
up. When a key or keys is help down, a metronome ( repeat ) code is
sent at a fixed rate.

The ST keyboards use a serial interface at 7.8125 K baud. They send a
scan code when a key is depressed or released. The software require to
convert input from the DEC keyboard to that used by the ST is straight
forward.

If you are willing to use your serial port, no modifications to the ST
or keyboard are required.  All it takes is a small, external, power
supply and a RJ11 ( modular phone plug ) to DB25 adapter.  The
limitation when using the serial port is that you can't use the ST as a
terminal with the external keyboard.  The midi port interface doesn't
have this limitation but it does require internal modifications to the
ST.

The power supply requirement is 200ma. at 12 V.  The voltage is
regulated internally so it isn't very critical.  A range from 10 V. to
15 V. seems OK, although you might have internal heat problems in the
keyboard at the upper end of that range. Suitable wall transformer type
supplies are available for less than $10.  Since I'm not going to buy a
Mega ST, my ST's power supply will have to handle 4 megabytes of memory
in the near future. I didn't want to further load the ST's already
marginal power supply with the extra keyboard.  

The midi port problem is that its baud rate is is hardwired into the
computer.  Changing the midi port's baud rate to 4800 baud is
straightforward, but it should only be done by someone with good
soldering skills and PC ( that's Printed Circuit, not Personal
Computer!  ) experience.

The modification uses one TTL IC, half a dozen short pieces of wire,
two solder connections to pins on existing IC's and one trace cut on
the top of the ST circuit board.  It isn't even necessary to remove the
metal shield on a 1040 ST, because everything you need to get at is
located under the disk drive.  Since this change will affect the
operation of the midi port, you may wish to mount a switch ( SPDT )
that selects either 4800 or the normal ( 31.25K )baud rate.

No external keyboard, unless it is simply an ST keyboard mounted in a
separate case, can replace the built in keyboard.  STs need the
mouse, joystick, and clock functions of the original keyboard.  An
external keyboard must simply work in parallel with the original
keyboard.

Software:

When you strike a key on the ST's keyboard, a scancode is sent from it
to a serial port on the main board.  This causes the serial port to
generate an interrupt.  The interrupt is serviced by a routine that:

        1. Gets the scan code sent by the keyboard
        2. Determines wether it is dealing with
           regular keys, shift keys or the mouse
        3. Performs the appropriate function.

As a result of a regular key press, the scancode and an ascii code  
( looked up in a set of tables ) are placed in a queue.  Shift codes
( right shift, left shift, control, caps lock, and alternate ) simply
cause a change the contents of a flag byte.  The contents of this byte
determine which of three tables is used for looking up the scan code
and if control or ALT are used as modifiers.

An external keyboard must duplicate, as much as is possible, these
regular key and shift functions and not disrupt the other ( mouse,
clock, and joystick ) keyboard functions.  Since the builtin keyboard
functions involve modification of data structures ( keyboard queue and
shift byte ) in memory, the external keyboard software can simply
modify the same data structures.  If the keyboard software was not
interrupt driven with these intermediate data stuctures, it would be
much more dificult to add an external keyboard.

The serial port, the keyboard port, and the midi port all use similar
interfaces.  This makes it easy to write an interrupt handler for the
serial or midi port that duplicate the  services provide by keyboard
port interrupt handler.  Most of the needed subroutines are already in
the ST's ROMs.  The code needed to add a keyboard is quite small, about
700 bytes. I'm sending uuencoded sources and binaries to
comp.{sources|binaries}. atari.st.

Bugs/Differences from the ST keyboard:

Well this an 'alpha' release, so it probably has a few unintended
'features'!  On the other hand, it is a small, simple, and straight
forward program.  I have been using the midi version for several weeks
on a 1040 ST and a friend has been using the serial port version on a
520 ST for two weeks.  We haven't found any problems.

I did have trouble when I tried using the external keyboard to replace
my mouse buttons.  I had to eliminate that 'feature' since it regularly
crashed the ST! The serial version won't work with a screen blanker
that monitors the keyboard/midi interrupt vector since it doesn't use
that vector!  The midi version works with idle 1.2, but it must be run
before idle is run.

I didn't put a lot of effort into handling the alt key because I very
rarely use it.  On the LK201, the alt key says 'Compose Character' and,
because of the way I handled it, it only affects the next key pressed. 
The only program I use that has a problem with alt is Uniterm.
Unfortunately I use Uniterm more than any other program ( thank you
Simon Poole!  ).  Uniterm doesn't use the normal alt flag, so I just do
the Uniterm alt stuff from my regular keyboard.

The LK201 keyboard is programmable, but I have not made any use of this
feature.  The midi interface is only 'RS423 compatible' for input, so
extra hardware would be required there.  The serial interface should be
able to talk to the keyboard, but I had no luck in my limited attempts
to do so.  Since I am comfortable with the keyboards default settings,
I made my interface input only.

Now let's consider the keyboard remappings: There is only one shift
code, so there is no way to set only one of two shift bits.  I don't
have any programs that distinguish between the the two shift keys,
but you may.  It can't be done with the DEC keyboard.  Another DEC
limitation, DEC keyboards don't have a backspace key or an escape
key in the main keypad.  I 'fixed' both these problems.

Delete is the key where backspace was and shift-delete acts as
backspace.  This works well when I use the ST as a terminal and with
emacs like editors.  Since some ST programs use backspace as delete
left, I also put backspace and delete on the two extra keys in the
middle of the pad above the cursor keys. 

DEC has this wierd < > key down between the z and the left shift, I
moved ~` down there, and put esc up in the top left hand corner where
~` was.  Note that < and > are shift-, and shift-.  respectively.
Actually DEC supports this change in their new 300 series of terminals.
They will even sell you a couple of new keytops to make it look
pretty. I just marked < and > on the ',' and '.' keycaps. 

A few other keys have moved around a bit, but that is about it.  There
are 20 function keys, so I mapped the top ten to the shifted function
key codes.  The keypad is identical, except for the notation on the top
four keys ( Pf1 - Pf4 instead of ( ) / * ) and the kp+ key that says
',' . There really is very little difference, and I find no problem,
other that feel, in switching between the two keyboards.  After typing
on the DEC keyboard, the ST feels very bad!  Now, on to the hardware
details.

Hardware:

The RJ11 ( standard modular telephone connector ) plug on the DEC
keyboard has four wires.  They are color coded black, red, green, and
yellow.  The red wire supplies power ( +12 V.  ) to the keyboard.  It
should be connected to the positive side of the power supply.  The
green wire is ground for both the power supply and the communications
lines.  It must be connnected to the negative side of the power supply.
The black wire is the RS-423 output from the keyboard.  The yellow wire
is the RS-423 input to the keyboard.  This interface does not use the
yellow wire.

For the serial port, I used an RJ11 to DB25 adapter that looks like an
oversized DB25 shell. Our computer center uses them for all our
terminals so that they can use RJ11 wall jacks.  I brought the power
wires in through a small hole that I melted in the shell, and did all
the wiring inside.  There were originally four wires connected to pins
2, 3, 7, and 20.  I cut all the wires and reconnected the ones for 3 (
black wire from keyboard) and  7 ( green wire from keyboard and power
supply negative lead ). Plug the keyboard into the RJ11 jack. 

Plug the DB25 into the serial port, power the keyboard, and run
serialkb.prg.  Serialkb.prg installs itself as the serial interrupt
driver the first time it is run.  It deinstalls itself when it is run
again and restores the original serial port interrupt handler.  The
small amount of memory used ( < 1KB ) will not be released until you
reboot.  It will create a new version of itself every other time you
run it.

The midi port (IN) connector is a five pin DIN male.  I actually used
the end of a cable from a defuct IBM PC keyboard. Connect the black
wire from the keyboard to pin 4 and the green wire to pin 5.  Watch out
for the wierd ordering, it isn't 1 2 3 4 5!  The keyboard power
connections are the same as for the serial port ( positive voltage to
red wire, negative to green ).  Note that the midi interface is not
RS-423 compatible, but that a RS-423 output should drive a midi input. 
It works well on my system, but 'your mileage may vary'.  Now lets go
through the hard part, changing the midi port's baud rate to 4800 baud.

Before starting this modification, reflect on the fact you will be
violating any Atari warantee and that you could, with suitable
carelessness or ignorance, trash your ST.  Don't try this, or any
other hardware modification, unless you know what you are doing and
are able to handle any damage you may cause.  I obviously can't help
you if you damage your system.  I hereby disclaim any and all
responsiblility for the correctness of the following instructions.
You should assume that they are designed to destroy your system 8^)!
These instructions are not a cookbook, they assume that you know
what you are doing.  If you don't, find somebody who does and get
them to help you!

The midi port uses an ACIA.  In its stock form the clock input to the
ACIA is 500 KHz and the ACIA is programmed to divide that clock by 16
giving a 31.25 K baud rate.  The keyboard ACIA uses the same clock, but
it is programmed to divide it by 64, giving 7.185 K baud. To get 4800
baud we need 16 or 64 times 4800 Hz at the midi ACIA clock input.  The
system has 8, 4, 2, and .5 Mhz clock signal available.  

A note of credit here, most of this information and the ROM listings
needed to complete this project came from 'Atari ST Internals',
published by Abacus.  This is, by far, the most useful ST book I own. 

A little playing around with a calculator shows 4MHz, divided by 13,
then divided by 64, gives 4807.7 Hz.  Good enough!  There is a 4 MHz
clock input to the 68901 MFP chip which is located near the ACIAs.  Now
all we need is a ciruit to divide that 4 Mhz clock by thirteen.

Dividing a TTL level clock signal by 13 is easy to do with a 4 bit
binary TTL counter chip with a parallel load function.  After a little
reading in my well worn 'TTL Cookbook' by Don Lancaster, and a few
minutes spent sorting through the chips I had available, I came up with
the following circuit:

                            ____________
                    grnd --|1    7    16|-- + 5V.
                         --|2    4    15|-- + 5V.
                         --|3    L    14|----------- 4 Mhz. INPUT
                    grnd --|4    S    13|------  ( pin 35, 68901 )
                   + 5V. --|5    1    12|--   | <- connect 13 and 11
                         --|6    9    11|------ 
307.6923 KHz OUTPUT -------|7    1    10|-- + 5V.
(pin 3, top 6850)   grnd --|8   TOP    9|-- + 5V.
                            ------------

I wired this circuit directly on the pins of the 74LS191 IC using
wire-wrap wire.  I soldered it after checking to make sure that it
did indeed divide by 13.  At first it didn't because I had wired pin
11 to pin 12, intead of to pin 13!  I always check and double check
every step of my work.  Careful checking along the way is tedious,
but it prevents much pain and suffering later.


Now, for the work inside the ST.  Take it apart and remove the floppy
drive ( this is for a 1040, I think the relevant chips are located in
the same area on the 520, near the serial port connector, but I
haven't made this modification to a 520.  Locate the MFP and the two
ACIAs.  On my 1040, the upper ( nearest the back ) ACIA is used for
the midi port.  There is a small trace connecting pins 3 and 4 ( the
clock inputs ) of both ACIA chips.  Cut it somewhere between the two
ACIAs.  Be careful to completely sever that trace and not to damage
any other traces.

To mount the 74LS191, bend pins 1 and 16 up above the top of the chip
and solder them to the leads of a bypass capacitor located above and
between the ACIA and MFP chips.  This holds the chip in place ( upside
down ) and provides power and ground connections.  It is easy to break
the pins, so be gentle.  Then carefully connect the INPUT by soldering
wire wrap wire directly to pin 35 of the MFP.  This pin is located
immediately below the Vss ( ground ) pin.  The ground is easy to
identify because it is a thick trace. Finally, connect the OUTPUT to
pin 3 of the midi ACIA using wire wrap wire.

Check and double check the wiring and the mounting of the TTL IC. Make
sure that none of its leads can touch anything conductive, for example,
the bottom shield on the disk drive!  Then put it all back together,
and boot it.  Be prepared to go back inside and fix any errors!  

Connect the keyboard to the midi port, power the keyboard, run the
program midikb.prg, and type on your new keyboard!  Midikb installs
itself as the midi port interrupt handler.  It uses 1 K of memory.
Since it does not interfere with the normal use of the system (as
far as I have been able to determine 8*)), I always have it
installed, but only power up the keyboard when I am using it.  To
deinstall, you must reboot the system.
  

	Mark Boyd, Computer Science
	Univ. of North Carolina at Asheville
	Asheville, NC 28804
	mbunca@ecsvax.uncecs.edu
	mark@ncsuvx.ncsu.edu

